RMarkdownによるドキュメント生成と共有

# RMarkdownによるドキュメント生成と共有
## 1. R言語とRMarkdownの基礎
### 紀ノ定　保礼
### 2021-12-11

---

# 紀ノ定 保礼（きのさだ やすのり）

- 所属
    + 静岡理工科大学　情報学部　講師

- 研究領域
    + 認知心理学、社会心理学を応用して、交通行動を研究しています
    + 最近は、テクノロジー × 心理　に興味あり

---

# 本講義の構成

1. R言語の基礎

2. R Markdownによるレポーティングの利点

3. R Markdownによるレポーティングの手続き

4. R Markdownの実習と質疑応答

5. 作成したドキュメントの共有

---

# R言語の基礎：参考資料

[森知晴先生の素晴らしい資料](https://tomoecon.github.io/R_for_graduate_thesis/)を、参考にさせていただきます。

---

# パッケージを用いない可視化

ヒストグラム<br>
.very_small[車の性能に関するデータセット`mtcars`の中の、燃費`mpg`変数を用いている]

```r
hist(mtcars$mpg)
```

]

散布図<br>
.very_small[車の性能に関するデータセット`mtcars`の中の、燃費`mpg`変数と、重量`wt`変数を用いている]

```r
plot(mtcars$mpg, mtcars$wt)
```

]

---

# 実習

以下の内容について、Wordを用いて、ショートレポートを書いてみましょう。<br>（分量は、A4 1枚以下でOK）

- 使用するデータ
  + [このリンクから](https://sistkanri-my.sharepoint.com/:f:/g/personal/kinosada_yasunori_sist_ac_jp/El7sVccNGhtIuDIPVHLKxRsB_YEVGiLHkVRrNOi7ptskwA?e=n6nh9Q)、**sample_dataset.csv**をダウンロードしてください
  + レポート内容
     - 要約統計量から分かること
     - その他の統計的分析から分かること（任意）
     - 可視化から分かること
     - その他自由

---

# できましたか？

---

# おっとすみません、<br>使用してもらうデータを間違えました！

---

# 実習（その2）

以下の内容について、Wordを用いて、ショートレポートを書いてみましょう。<br>（分量は、A4 1枚以下でOK）

- 使用するデータ
  + [このリンクから](https://sistkanri-my.sharepoint.com/:f:/g/personal/kinosada_yasunori_sist_ac_jp/El7sVccNGhtIuDIPVHLKxRsB_YEVGiLHkVRrNOi7ptskwA?e=n6nh9Q)、**DS_dataset.csv**をダウンロードしてください
  + レポート内容
     - 要約統計量から分かること
     - その他の統計的分析から分かること（任意）
     - 可視化から分かること
     - その他自由

---

# 今度こそ、できましたか？

---

<img height = "600" src = img/data_zaurus.png>
可視化は大事（[オリジナルサイトのリンク](http://www.thefunctionalart.com/2016/08/download-datasaurus-never-trust-summary.html)）

---

# ところで、レポートを作り直すの、<br>面倒じゃなかったですか？

---

# Then, you are ready to use R Markdown !

---

# おすすめ図書

.pull-right[
<img height = "400" src = https://gihyo.jp/assets/images/cover/2021/thumb/TH160_9784297121709.jpg>

---

# おすすめWeb資料（しかも無料で閲覧可）

.pull-right[
<img height = "400" src = https://gedevan-aleksizde.github.io/rmarkdown-cookbook/images/cover.png>

---

### ドキュメント例

---

### Google Colaboratoryによるドキュメント例

これは**notebook**と呼ばれるドキュメント

<u>[リンクはこちら](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&cad=rja&uact=8&ved=2ahUKEwig9ueuwNj0AhX_hlYBHaXGARMQFnoECAMQAQ&url=https%3A%2F%2Fcolab.research.google.com%2Fnotebooks%2Fwelcome.ipynb%3Fhl%3Dja&usg=AOvVaw0qrT1c7i_vNFAUuRBp9c6M)</u>

---

セルをダブルクリックして見てみよう<br>
　→　HTMLタグによって装飾されている

---

Markdownには色々と種類があるが、<br>
<u>R Markdownで</u>用いられているのは**Pandocの**Markdown

詳細は<u>[こちらから](https://pandoc.org/MANUAL.html#pandocs-markdown)</u>

---

**PandocのMarkdown**記法の例

<img width = "550" src = "img/pandocmd.png">
.small[[R Markdownチートシート](https://www.rstudio.com/wp-content/uploads/2016/11/Rmarkdown-cheatsheet-2.0_ja.pdf)より
]

---

### Google Colaboratory上で練習

Google Colaboratory（Python環境）を使うには、<u>[このリンクから](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&cad=rja&uact=8&ved=2ahUKEwig9ueuwNj0AhX_hlYBHaXGARMQFnoECAMQAQ&url=https%3A%2F%2Fcolab.research.google.com%2Fnotebooks%2Fwelcome.ipynb%3Fhl%3Dja&usg=AOvVaw0qrT1c7i_vNFAUuRBp9c6M)</u>

Googleアカウントでログイン済みの人は、<u>[このリンクから](https://colab.research.google.com/notebook#create=true&language=r)</u>R環境が使える<br>
.too_small[ただしbase Rしか使えない]

様々なパッケージがインストールされたR環境を使うには、一手間要るが、<u>[このリンク](https://htsuda.net/stats/colab.html)</u>を参照。

---

## RStudio上でのドキュメント生成

.small[
1. Rmdファイルを準備
2. 文章（Markdown記法で）や、Rチャンク（後述）を書く
3. Knitしてレンダリング（後述）
4. 出力されたドキュメントを確認し、必要に応じて2～4をループ
]

[R Markdownチートシート](https://www.rstudio.com/wp-content/uploads/2016/11/Rmarkdown-cheatsheet-2.0_ja.pdf)より

---

### ドキュメント一覧

[R Markdownチートシート](https://www.rstudio.com/wp-content/uploads/2016/11/Rmarkdown-cheatsheet-2.0_ja.pdf)より

---

### もしかして、某社Office製品、いらない...？

- データ整形にExcelはいらない（Rがある）

- データ可視化にExcelはいらない（Rがある）

- データ分析にExcelはいらない（Rがある。ただし**HAD**は除く）

- レポーティングやプレゼンテーションに、WordやPowerPointはいらない<br>（htmlやpdfで問題ない）
    + やむなく必要に迫られた際は、WordやPowerPointでレンダリング可能

## PDF化する際の注意点

<img width = "450" src = "img/tinytex.png">
.small[そんなときは`tinytex`]

---

## プレゼンテーション用ドキュメント

デフォルトで以下の形式が用意されている

- ioslides: ブラウザで閲覧可能なHTML形式
- Slidy: ブラウザで閲覧可能なHTML形式
- Beamer: PDF形式（TeXによる）
- Microsoft PowerPoint

***************

その他、[xaringanパッケージ](https://github.com/yihui/xaringan)により、拡張性の高いプレゼンテーション用<br>ドキュメント作成も可能

本資料も<u>`xaringan`</u>で作成

---

# R Markdownによる<br>レポーティングの利点

---

- ヒューマンエラーや手間の低減

<img width = "600" src = "img/whatisrmd2.PNG">
[R Markdownチートシート](https://www.rstudio.com/wp-content/uploads/2016/11/Rmarkdown-cheatsheet-2.0_ja.pdf)より

- `Shiny`等との連携によるインタラクティブなレポーティング

- Gitによるバージョン管理やGitHubによる共同作業との相性

- 「ドキュメント構造」の意識による、思考の整理.very_small[（個人的意見）]

---

## R Markdownが<u>ないとき</u>

数値や図表を**手作業で**レポートへ反映させる

→　入力ミス、違う図表の挿入など、**追跡困難なヒューマンエラー**の恐れ

---

---

## R Markdownが<u>あるとき</u>

<img width = "680" src = "img/example_rmd.png">
.very_small[[日本社会心理学会第5回春の方法論セミナー](https://kazutan.github.io/JSSP2018_spring/)]

- .Rmdファイルに記述した内容が**自動的に**レポートになる
- 適切にバージョン管理していれば、ミスがあっても、特定・修正できる

---

[参考映像：a reproducible workflow](https://youtu.be/s3JldKoA0zw)

---

## `Shiny`による、インタラクティブな<br>レポーティング

```r
library(tidyverse)
library(plotly)

g = ggplot(data = mtcars, mapping = aes(x = factor(am), y = wt, colour = factor(am))) +
  geom_boxplot(alpha = 0.4)

ggplotly(g)
```

<div id="htmlwidget-f188761b0a3cc0ba7b40" style="width:450px;height:250px;" class="plotly html-widget"></div>
<script type="application/json" data-for="htmlwidget-f188761b0a3cc0ba7b40">{"x":{"data":[{"x":[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],"y":[3.44,3.15,3.215,3.73,3.46,3.57,3.19,5.345,3.44,3.44,4.07,2.465,3.78,5.25,5.424,3.845,3.52,3.435,3.84],"hoverinfo":"y","type":"box","fillcolor":"rgba(255,255,255,0.4)","marker":{"opacity":null,"outliercolor":"rgba(0,0,0,1)","line":{"width":1.88976377952756,"color":"rgba(0,0,0,1)"},"size":5.66929133858268},"line":{"color":"rgba(248,118,109,1)","width":1.88976377952756},"name":"0","legendgroup":"0","showlegend":true,"xaxis":"x","yaxis":"y","frame":null},{"x":[2,2,2,2,2,2,2,2,2,2,2,2,2],"y":[2.62,2.875,2.32,1.835,3.17,2.2,1.615,1.513,1.935,2.14,2.78,2.77,3.57],"hoverinfo":"y","type":"box","fillcolor":"rgba(255,255,255,0.4)","marker":{"opacity":null,"outliercolor":"rgba(0,0,0,1)","line":{"width":1.88976377952756,"color":"rgba(0,0,0,1)"},"size":5.66929133858268},"line":{"color":"rgba(0,191,196,1)","width":1.88976377952756},"name":"1","legendgroup":"1","showlegend":true,"xaxis":"x","yaxis":"y","frame":null}],"layout":{"margin":{"t":34.7866927592955,"r":7.30593607305936,"b":48.7410306588389,"l":31.4155251141553},"plot_bgcolor":"rgba(235,235,235,1)","paper_bgcolor":"rgba(255,255,255,1)","font":{"color":"rgba(0,0,0,1)","family":"","size":14.6118721461187},"xaxis":{"domain":[0,1],"automargin":true,"type":"linear","autorange":false,"range":[0.4,2.6],"tickmode":"array","ticktext":["0","1"],"tickvals":[1,2],"categoryorder":"array","categoryarray":["0","1"],"nticks":null,"ticks":"outside","tickcolor":"rgba(51,51,51,1)","ticklen":3.65296803652968,"tickwidth":0.66417600664176,"showticklabels":true,"tickfont":{"color":"rgba(77,77,77,1)","family":"","size":11.689497716895},"tickangle":-0,"showline":false,"linecolor":null,"linewidth":0,"showgrid":true,"gridcolor":"rgba(255,255,255,1)","gridwidth":0.66417600664176,"zeroline":false,"anchor":"y","title":{"text":"factor(am)","font":{"color":"rgba(0,0,0,1)","family":"","size":14.6118721461187}},"hoverformat":".2f"},"yaxis":{"domain":[0,1],"automargin":true,"type":"linear","autorange":false,"range":[1.31745,5.61955],"tickmode":"array","ticktext":["2","3","4","5"],"tickvals":[2,3,4,5],"categoryorder":"array","categoryarray":["2","3","4","5"],"nticks":null,"ticks":"outside","tickcolor":"rgba(51,51,51,1)","ticklen":3.65296803652968,"tickwidth":0.66417600664176,"showticklabels":true,"tickfont":{"color":"rgba(77,77,77,1)","family":"","size":11.689497716895},"tickangle":-0,"showline":false,"linecolor":null,"linewidth":0,"showgrid":true,"gridcolor":"rgba(255,255,255,1)","gridwidth":0.66417600664176,"zeroline":false,"anchor":"x","title":{"text":"wt","font":{"color":"rgba(0,0,0,1)","family":"","size":14.6118721461187}},"hoverformat":".2f"},"shapes":[{"type":"rect","fillcolor":null,"line":{"color":null,"width":0,"linetype":[]},"yref":"paper","xref":"paper","x0":0,"x1":1,"y0":0,"y1":1}],"showlegend":true,"legend":{"bgcolor":"rgba(255,255,255,1)","bordercolor":"transparent","borderwidth":1.88976377952756,"font":{"color":"rgba(0,0,0,1)","family":"","size":11.689497716895},"title":{"text":"factor(am)","font":{"color":"rgba(0,0,0,1)","family":"","size":14.6118721461187}}},"hovermode":"closest","barmode":"relative"},"config":{"doubleClick":"reset","modeBarButtonsToAdd":["hoverclosest","hovercompare"],"showSendToCloud":false},"source":"A","attrs":{"3dc041ca2c25":{"x":{},"y":{},"colour":{},"type":"box"}},"cur_data":"3dc041ca2c25","visdat":{"3dc041ca2c25":["function (y) ","x"]},"highlight":{"on":"plotly_click","persistent":false,"dynamic":false,"selectize":false,"opacityDim":0.2,"selected":{"opacity":1},"debounce":0},"shinyEvents":["plotly_hover","plotly_click","plotly_selected","plotly_relayout","plotly_brushed","plotly_brushing","plotly_clickannotation","plotly_doubleclick","plotly_deselect","plotly_afterplot","plotly_sunburstclick"],"base_url":"https://plot.ly"},"evals":[],"jsHooks":[]}</script>

---

# 3. R Markdownによる<br>レポーティングの手続き

---

とりあえずチートシートを手元に置きましょう

---

## 準備

新規.Rmdファイルを用意し、ドキュメントの出力形式を選ぶ（後で変更可）

---

個人的なおすすめは、`rmdformats`パッケージをインストールし、<br>テンプレートを利用すること

特に**readthedown**や**robobook**テンプレートが便利。

---

論文も書けちゃう

<img width = "750" src = "img/templates.png">
.small[
- `{papaja}`パッケージ
    + APAスタイルに特化したテンプレート
- `{rticles}`パッケージ
    + **Elsevier**, **Springer**, **PNAS**など、主要な出版社・雑誌に対応
]

.very_small[詳しくは、[アカデミアのためのRSTUDIO](https://ytake2.github.io/create.manuscript/RStudio_for_Academia.html)を参照]

---

例えば**Springer**スタイルの場合（`rticles`パッケージ）<br>.small[（別に`.tex`ファイルが作成されている）]

---

readthedownテンプレートの場合（`rmdformats`パッケージ）

---

## フロントマター（YAMLヘッド項目）

フロントマターに、ドキュメントのプロパティ情報や<br>.small[（例：日付、製作者）]、出力形式の設定を書く

---

### 個人的によく使うYAMLヘッダ項目

```yaml
---
title: "Ritsumeikan_Rmd_20211213"
subtitle: "hogehoge"
author: "Yasunori Kinosada"
date: "2021-12-11" #自動で本日の日付を取得するなら、`r Sys.Date()`
output:
  rmdformats::readthedown:
    highlight: zenburn #コードシンタックスのハイライト方法
    md_extensions: -ascii_identifiers #マルチバイト文字を用いる場合のおまじない
    self_contained: true #jsやcss，画像データなどをhtmlファイルに埋め込む
    lightbox: true #画像をクリックしたらポップアウトさせる
    toc: true #メニュー（toc: table of contents）を設ける
    toc_float: true #tocを設けた場合に、ページ冒頭ではなく、サイドメニュー化
    toc_depth: 3 #tocに反映させる見出しの階層数
---
```

もちろん他にもたくさんある

---
### YAMLヘッダ項目一覧

多すぎるので全容は@kazutanの記事を参照<br>
.very_small[[R Markdownのhtml_documentで指定できるyamlヘッダ項目について](https://qiita.com/kazutan/items/726e03dfcef1615ae999)]

---

## PandocのMarkdown記法で地の文を書く

---

## Visual Editorで編集も可能

---

## コードチャンク

地の文ではない<u>コード部分</u>は、まとまり単位で**チャンク**の<br>中に書き、**チャンクオプション**を併用することで、挙動を操作

---

### 新しいチャンクの準備

書きたい言語と対応するチャンクを選ぶ

---

### `{knitr}`パッケージがサポートしている<br>言語エンジン一覧

```r
names(knitr::knit_engines$get())
```

```
##  [1] "awk"       "bash"      "coffee"    "gawk"      "groovy"    "haskell"  
##  [7] "lein"      "mysql"     "node"      "octave"    "perl"      "psql"     
## [13] "Rscript"   "ruby"      "sas"       "scala"     "sed"       "sh"       
## [19] "stata"     "zsh"       "highlight" "Rcpp"      "tikz"      "dot"      
## [25] "c"         "cc"        "fortran"   "fortran95" "asy"       "cat"      
## [31] "asis"      "stan"      "block"     "block2"    "js"        "css"      
## [37] "sql"       "go"        "python"    "julia"     "sass"      "scss"     
## [43] "R"         "bslib"     "targets"   "glue"      "glue_sql"  "gluesql"
```

---

### チャンク生成のショートカット
<img width = "800" src = "img/chunk_shortcut.png">

---

- .small[なおチャンクラベルには、**アルファベット**、**数字**、**ダッシュ**`-`のみ使用推奨]<br>
- .small[同一.Rmdファイル内で、同じチャンクラベルは使用不可]

---

### チャンクオプション一覧

[R Markdownチートシート](https://www.rstudio.com/wp-content/uploads/2016/11/Rmarkdown-cheatsheet-2.0_ja.pdf)より

---

各チャンクで指定するのが面倒なら、グローバルな設定も可<br>　↓　使用例

---

### GUIでチャンクオプションを設定可能
<img width = "650" src = "img/setting_chunk.png">

**? Chunk options**を押すと、Webページが開いて詳細を確認可

---

### チャンク単位で実行可能
<img width = "800" src = "img/each_chunk.png">

---

実行時やレンダリング時の設定は変更可能

---

## 見出し

見出し（`#`の数で階層化可能）やチャンク名を付けると、<br>メニューが生成される

---

## 画像の挿入

Rコード.small[（`ggplot2`パッケージ等）]で画像を生成するのではなく、<br><u>既存の画像を挿入する</u>場合

- 方法1：Markdown記法

```r
![alt text or image title](path/to/image)
```
```r
![alt text or image title][hogehoge]
[hogehoge]: path/to/image
```
```r
<img src = "path/to/image" alt = "hogehoge" title="fugafuga" width="200" height="300">
```

Markdown記法なので、文章扱い。コードチャンク**外**に書く

---

- 方法2：`knitr`パッケージの`include_graphics()`

Rコードなので、コードチャンク**内**に書く

画像のプロパティを、チャンクオプションで様々に操作可

---

## 表の生成

- 方法1：`knitr::kable()`（とりあえずこれでいい）

```r
knitr::kable(x = head(mtcars, 2),
             format = "html",
             digits = 2,
             align = "c",
             caption = "two rows of mtcars dataset")
```

<table>
<caption>two rows of mtcars dataset</caption>
 <thead>
  <tr>
   <th style="text-align:left;">   </th>
   <th style="text-align:center;"> mpg </th>
   <th style="text-align:center;"> cyl </th>
   <th style="text-align:center;"> disp </th>
   <th style="text-align:center;"> hp </th>
   <th style="text-align:center;"> drat </th>
   <th style="text-align:center;"> wt </th>
   <th style="text-align:center;"> qsec </th>
   <th style="text-align:center;"> vs </th>
   <th style="text-align:center;"> am </th>
   <th style="text-align:center;"> gear </th>
   <th style="text-align:center;"> carb </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:left;"> Mazda RX4 </td>
   <td style="text-align:center;"> 21 </td>
   <td style="text-align:center;"> 6 </td>
   <td style="text-align:center;"> 160 </td>
   <td style="text-align:center;"> 110 </td>
   <td style="text-align:center;"> 3.9 </td>
   <td style="text-align:center;"> 2.62 </td>
   <td style="text-align:center;"> 16.46 </td>
   <td style="text-align:center;"> 0 </td>
   <td style="text-align:center;"> 1 </td>
   <td style="text-align:center;"> 4 </td>
   <td style="text-align:center;"> 4 </td>
  </tr>
  <tr>
   <td style="text-align:left;"> Mazda RX4 Wag </td>
   <td style="text-align:center;"> 21 </td>
   <td style="text-align:center;"> 6 </td>
   <td style="text-align:center;"> 160 </td>
   <td style="text-align:center;"> 110 </td>
   <td style="text-align:center;"> 3.9 </td>
   <td style="text-align:center;"> 2.88 </td>
   <td style="text-align:center;"> 17.02 </td>
   <td style="text-align:center;"> 0 </td>
   <td style="text-align:center;"> 1 </td>
   <td style="text-align:center;"> 4 </td>
   <td style="text-align:center;"> 4 </td>
  </tr>
</tbody>
</table>
---

- 方法2：自力で書く
    + `knitr::kable()`を、Markdown形式で出力させると...

実はこれが、表のMarkdown記法

- `:-----`　　左揃え
- `:----:`　　中央揃え
- `-----:`　　右揃え

---

## Data.frameの表示

行数が少なければ`knitr::kable()`でよいが、多いと場所をとる

→　フロントマターで、`df_print`を`"paged"`に変更

---

### 行が多すぎて省略される場合でも...

---

クラスを`data.frame`にしてしまえば、<br>`df_print: "paged"`で全行表示可

---

## インラインコード・数式の表示

値を**書き写す**手間・必要が一切不要

TeXと同じ記法で数式を書ける

---

## 書きあがったらKnit（レンダリング）

outputのフォーマットに応じて出力される

---

どんっ！

---

実習：好きなデータセットを用いて、HTMLドキュメントを書いてみよう